package cn.cleanarch.infra.idp.pms.service;

import cn.cleanarch.infra.idp.commons.domain.dto.PageResult;
import cn.cleanarch.infra.idp.pms.domain.dto.*;
import cn.cleanarch.infra.idp.pms.domain.entity.DesignFile;
import cn.cleanarch.infra.idp.pms.domain.entity.DesignFileVersion;
import cn.cleanarch.infra.idp.pms.domain.query.DesignFileQuery;
import cn.cleanarch.infra.idp.pms.domain.query.DesignFileVersionQuery;

import java.util.List;

/**
 * 设计文件服务接口
 */
public interface DesignFileService {

    /**
     * 分页查询设计文件
     * 
     * @param query 查询条件
     * @return 分页结果
     */
    PageResult<DesignFileDTO> pageQuery(DesignFileQuery query);
    
    /**
     * 分页查询设计文件版本
     * 
     * @param query 查询条件
     * @return 分页结果
     */
    PageResult<DesignFileVersionDTO> pageQueryVersion(DesignFileVersionQuery query);
    
    /**
     * 根据ID获取设计文件
     * 
     * @param id 文件ID
     * @return 设计文件
     */
    DesignFile getById(Long id);
    
    /**
     * 创建设计文件
     * 
     * @param file 设计文件数据
     * @return 设计文件
     */
    DesignFile create(DesignFile file);
    
    /**
     * 更新设计文件
     * 
     * @param file 设计文件数据
     * @return 设计文件
     */
    DesignFile update(DesignFile file);
    
    /**
     * 删除设计文件
     * 
     * @param id 文件ID
     */
    void delete(Long id);
    
    /**
     * 获取标签列表
     * 
     * @return 标签列表
     */
    List<DesignFileTagDTO> getTags();
    
    /**
     * 创建设计文件标签
     * 
     * @param tag 标签数据
     * @return 标签
     */
    DesignFileTagDTO createTag(DesignFileTagDTO tag);
    
    /**
     * 更新设计文件标签
     * 
     * @param tag 标签数据
     * @return 标签
     */
    DesignFileTagDTO updateTag(DesignFileTagDTO tag);
    
    /**
     * 删除设计文件标签
     * 
     * @param id 标签ID
     */
    void deleteTag(Long id);
    
    /**
     * 获取文件类型选项
     * 
     * @return 文件类型选项
     */
    List<FileTypeOptionDTO> getFileTypeOptions();
    
    /**
     * 安全扫描文件
     * 
     * @param id 文件ID
     * @return 扫描结果
     */
    void scanFileSecurity(Long id);
    
    /**
     * 转换实体类为DTO
     * 
     * @param entity 实体类
     * @return DTO
     */
    DesignFileDTO convertToDTO(DesignFile entity);

    /**
     * 获取文件下载URL（基于当前版本ID）
     * 
     * @param id 文件ID（会根据currentVersionId查找当前版本）
     * @return 下载URL
     */
    String getFileDownloadUrl(Long id);

    /**
     * 批量上传文件
     * 
     * @param files 文件数组
     * @return 文件信息列表
     */
    List<DesignFileDTO> uploadFilesBatch(org.springframework.web.multipart.MultipartFile[] files);

    /**
     * 提供HTML压缩包子路径资源进行预览
     * 
     * @param fileId 文件ID
     * @param subPath 子路径（如: /css/style.css, /js/main.js等）
     * @param response HTTP响应
     * @throws Exception 异常
     */
    void serveFileSubPath(Long fileId, String subPath, jakarta.servlet.http.HttpServletResponse response) throws Exception;

    /**
     * 提供版本HTML压缩包子路径资源进行预览
     * 
     * @param versionId 版本ID
     * @param subPath 子路径（如: /css/style.css, /js/main.js等）
     * @param response HTTP响应
     * @throws Exception 异常
     */
    void serveVersionSubPath(Long versionId, String subPath, jakarta.servlet.http.HttpServletResponse response) throws Exception;

    /**
     * 清理过期的解压文件
     * 
     * @param maxAge 最大保留时间（毫秒）
     */
    void cleanupExpiredExtractFiles(long maxAge);

    /**
     * 仅上传文件，不绑定业务信息
     * 
     * @param file 上传的文件
     * @return 包含文件ID的DTO
     */
    DesignFileDTO uploadFileOnly(org.springframework.web.multipart.MultipartFile file);

    /**
     * 获取设计文件的所有版本
     * 
     * @param fileId 文件ID
     * @return 版本列表
     */
    List<DesignFileVersionDTO> getVersionsByFileId(Long fileId);

    /**
     * 根据文件ID和版本号获取特定版本
     * 
     * @param fileId 文件ID
     * @param versionNumber 版本号
     * @return 版本信息
     */
    DesignFileVersionDTO getVersionByFileIdAndVersionNumber(Long fileId, String versionNumber);

    /**
     * 根据版本ID获取版本信息（优化版本）
     * 
     * @param versionId 版本ID
     * @return 版本信息
     */
    DesignFileVersionDTO getVersionById(Long versionId);

    /**
     * 根据版本ID获取对应的文件ID
     * 
     * @param versionId 版本ID
     * @return 文件ID，如果版本不存在则返回null
     */
    Long getFileIdByVersionId(Long versionId);

    /**
     * 根据currentVersionId获取对应的文件ID（安全预览用）
     * 
     * @param currentVersionId 当前版本ID
     * @return 文件ID，如果版本不存在则返回null
     */
    Long getFileIdByCurrentVersionId(Long currentVersionId);

    /**
     * 创建新的文件版本
     * 
     * @param fileId 文件ID
     * @param versionDTO 版本信息
     * @return 版本信息
     */
    DesignFileVersionDTO createVersion(Long fileId, DesignFileVersionDTO versionDTO);

    /**
     * 更新文件版本信息
     * 
     * @param versionId 版本ID
     * @param versionDTO 版本信息
     * @return 版本信息
     */
    DesignFileVersionDTO updateVersion(Long versionId, DesignFileVersionDTO versionDTO);

    /**
     * 删除文件版本
     * 
     * @param versionId 版本ID
     */
    void deleteVersion(Long versionId);

    /**
     * 恢复到指定版本
     * 
     * @param fileId 文件ID
     * @param versionNumber 版本号
     * @return 恢复后的文件信息
     */
    DesignFileDTO restoreToVersion(Long fileId, String versionNumber);

    /**
     * 转换DesignFileVersion实体类为DTO
     * 
     * @param entity DesignFileVersion实体类
     * @return DesignFileVersionDTO
     */
    DesignFileVersionDTO convertToDTO(DesignFileVersion entity);

    /**
     * 生成版本预览数据（基于版本表数据）
     * 
     * @param versionId 版本ID
     * @return 版本预览数据
     */
    DesignFileVersionPreviewDTO generateVersionPreviewData(Long versionId);

    /**
     * 根据版本ID获取文件下载URL（支持多版本下载）
     * 
     * @param versionId 版本ID
     * @return 下载URL
     */
    String getVersionDownloadUrl(Long versionId);
}
